<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Reading and Writing Files</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
<link rel="home" href="index.html" title="GnomeVFS - Filesystem Abstraction library">
<link rel="up" href="gnome-vfs-basic-file-ops.html" title="File Operations">
<link rel="prev" href="gnome-vfs-2.0-gnome-vfs-file-basic-ops.html" title="Basic File Operations">
<link rel="next" href="gnome-vfs-2.0-gnome-vfs-file-trunc-ops.html" title="Truncating Files">
<meta name="generator" content="GTK-Doc V1.15.1 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
<tr valign="middle">
<td><a accesskey="p" href="gnome-vfs-2.0-gnome-vfs-file-basic-ops.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
<td><a accesskey="u" href="gnome-vfs-basic-file-ops.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
<th width="100%" align="center">GnomeVFS - Filesystem Abstraction library</th>
<td><a accesskey="n" href="gnome-vfs-2.0-gnome-vfs-file-trunc-ops.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
</tr>
<tr><td colspan="5" class="shortcuts">
<a href="#gnome-vfs-2.0-gnome-vfs-file-rw-ops.synopsis" class="shortcut">Top</a>
                   | 
                  <a href="#gnome-vfs-2.0-gnome-vfs-file-rw-ops.description" class="shortcut">Description</a>
</td></tr>
</table>
<div class="refentry">
<a name="gnome-vfs-2.0-gnome-vfs-file-rw-ops"></a><div class="titlepage"></div>
<div class="refnamediv"><table width="100%"><tr>
<td valign="top">
<h2><span class="refentrytitle"><a name="gnome-vfs-2.0-gnome-vfs-file-rw-ops.top_of_page"></a>Reading and Writing Files</span></h2>
<p>Reading and Writing Files — Reading from and writing to open file handles.</p>
</td>
<td valign="top" align="right"></td>
</tr></table></div>
<div class="refsynopsisdiv">
<a name="gnome-vfs-2.0-gnome-vfs-file-rw-ops.synopsis"></a><h2>Synopsis</h2>
<pre class="synopsis">enum                <a class="link" href="gnome-vfs-2.0-gnome-vfs-file-rw-ops.html#GnomeVFSSeekPosition" title="enum GnomeVFSSeekPosition">GnomeVFSSeekPosition</a>;
<a class="link" href="gnome-vfs-2.0-gnome-vfs-result.html#GnomeVFSResult" title="enum GnomeVFSResult"><span class="returnvalue">GnomeVFSResult</span></a>      <a class="link" href="gnome-vfs-2.0-gnome-vfs-file-rw-ops.html#gnome-vfs-read" title="gnome_vfs_read ()">gnome_vfs_read</a>                      (<em class="parameter"><code><span class="type">GnomeVFSHandle</span> *handle</code></em>,
                                                         <em class="parameter"><code><span class="type">gpointer</span> buffer</code></em>,
                                                         <em class="parameter"><code><a class="link" href="gnome-vfs-2.0-gnome-vfs-file-size.html#GnomeVFSFileSize" title="GnomeVFSFileSize"><span class="type">GnomeVFSFileSize</span></a> bytes</code></em>,
                                                         <em class="parameter"><code><a class="link" href="gnome-vfs-2.0-gnome-vfs-file-size.html#GnomeVFSFileSize" title="GnomeVFSFileSize"><span class="type">GnomeVFSFileSize</span></a> *bytes_read</code></em>);
<a class="link" href="gnome-vfs-2.0-gnome-vfs-result.html#GnomeVFSResult" title="enum GnomeVFSResult"><span class="returnvalue">GnomeVFSResult</span></a>      <a class="link" href="gnome-vfs-2.0-gnome-vfs-file-rw-ops.html#gnome-vfs-write" title="gnome_vfs_write ()">gnome_vfs_write</a>                     (<em class="parameter"><code><span class="type">GnomeVFSHandle</span> *handle</code></em>,
                                                         <em class="parameter"><code><span class="type">gconstpointer</span> buffer</code></em>,
                                                         <em class="parameter"><code><a class="link" href="gnome-vfs-2.0-gnome-vfs-file-size.html#GnomeVFSFileSize" title="GnomeVFSFileSize"><span class="type">GnomeVFSFileSize</span></a> bytes</code></em>,
                                                         <em class="parameter"><code><a class="link" href="gnome-vfs-2.0-gnome-vfs-file-size.html#GnomeVFSFileSize" title="GnomeVFSFileSize"><span class="type">GnomeVFSFileSize</span></a> *bytes_written</code></em>);
<a class="link" href="gnome-vfs-2.0-gnome-vfs-result.html#GnomeVFSResult" title="enum GnomeVFSResult"><span class="returnvalue">GnomeVFSResult</span></a>      <a class="link" href="gnome-vfs-2.0-gnome-vfs-file-rw-ops.html#gnome-vfs-seek" title="gnome_vfs_seek ()">gnome_vfs_seek</a>                      (<em class="parameter"><code><span class="type">GnomeVFSHandle</span> *handle</code></em>,
                                                         <em class="parameter"><code><a class="link" href="gnome-vfs-2.0-gnome-vfs-file-rw-ops.html#GnomeVFSSeekPosition" title="enum GnomeVFSSeekPosition"><span class="type">GnomeVFSSeekPosition</span></a> whence</code></em>,
                                                         <em class="parameter"><code><a class="link" href="gnome-vfs-2.0-gnome-vfs-file-size.html#GnomeVFSFileOffset" title="GnomeVFSFileOffset"><span class="type">GnomeVFSFileOffset</span></a> offset</code></em>);
<a class="link" href="gnome-vfs-2.0-gnome-vfs-result.html#GnomeVFSResult" title="enum GnomeVFSResult"><span class="returnvalue">GnomeVFSResult</span></a>      <a class="link" href="gnome-vfs-2.0-gnome-vfs-file-rw-ops.html#gnome-vfs-tell" title="gnome_vfs_tell ()">gnome_vfs_tell</a>                      (<em class="parameter"><code><span class="type">GnomeVFSHandle</span> *handle</code></em>,
                                                         <em class="parameter"><code><a class="link" href="gnome-vfs-2.0-gnome-vfs-file-size.html#GnomeVFSFileSize" title="GnomeVFSFileSize"><span class="type">GnomeVFSFileSize</span></a> *offset_return</code></em>);
<a class="link" href="gnome-vfs-2.0-gnome-vfs-result.html#GnomeVFSResult" title="enum GnomeVFSResult"><span class="returnvalue">GnomeVFSResult</span></a>      <a class="link" href="gnome-vfs-2.0-gnome-vfs-file-rw-ops.html#gnome-vfs-forget-cache" title="gnome_vfs_forget_cache ()">gnome_vfs_forget_cache</a>              (<em class="parameter"><code><span class="type">GnomeVFSHandle</span> *handle</code></em>,
                                                         <em class="parameter"><code><a class="link" href="gnome-vfs-2.0-gnome-vfs-file-size.html#GnomeVFSFileOffset" title="GnomeVFSFileOffset"><span class="type">GnomeVFSFileOffset</span></a> offset</code></em>,
                                                         <em class="parameter"><code><a class="link" href="gnome-vfs-2.0-gnome-vfs-file-size.html#GnomeVFSFileSize" title="GnomeVFSFileSize"><span class="type">GnomeVFSFileSize</span></a> size</code></em>);
</pre>
</div>
<div class="refsect1">
<a name="gnome-vfs-2.0-gnome-vfs-file-rw-ops.description"></a><h2>Description</h2>
<p>
  Reading and writing operations are explained, also <a class="link" href="gnome-vfs-2.0-gnome-vfs-file-rw-ops.html#gnome-vfs-seek" title="gnome_vfs_seek ()"><code class="function">gnome_vfs_seek()</code></a>, which
  is used to move the file pointer inside the file.
</p>
</div>
<div class="refsect1">
<a name="gnome-vfs-2.0-gnome-vfs-file-rw-ops.details"></a><h2>Details</h2>
<div class="refsect2">
<a name="GnomeVFSSeekPosition"></a><h3>enum GnomeVFSSeekPosition</h3>
<pre class="programlisting">typedef enum {
        GNOME_VFS_SEEK_START,
        GNOME_VFS_SEEK_CURRENT,
        GNOME_VFS_SEEK_END
} GnomeVFSSeekPosition;
</pre>
<p>
This is used to specify the start position for seek operations.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><a name="GNOME-VFS-SEEK-START:CAPS"></a><span class="term"><code class="literal">GNOME_VFS_SEEK_START</code></span></p></td>
<td>Start of the file.
</td>
</tr>
<tr>
<td><p><a name="GNOME-VFS-SEEK-CURRENT:CAPS"></a><span class="term"><code class="literal">GNOME_VFS_SEEK_CURRENT</code></span></p></td>
<td>Current position.
</td>
</tr>
<tr>
<td><p><a name="GNOME-VFS-SEEK-END:CAPS"></a><span class="term"><code class="literal">GNOME_VFS_SEEK_END</code></span></p></td>
<td>End of the file.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="gnome-vfs-read"></a><h3>gnome_vfs_read ()</h3>
<pre class="programlisting"><a class="link" href="gnome-vfs-2.0-gnome-vfs-result.html#GnomeVFSResult" title="enum GnomeVFSResult"><span class="returnvalue">GnomeVFSResult</span></a>      gnome_vfs_read                      (<em class="parameter"><code><span class="type">GnomeVFSHandle</span> *handle</code></em>,
                                                         <em class="parameter"><code><span class="type">gpointer</span> buffer</code></em>,
                                                         <em class="parameter"><code><a class="link" href="gnome-vfs-2.0-gnome-vfs-file-size.html#GnomeVFSFileSize" title="GnomeVFSFileSize"><span class="type">GnomeVFSFileSize</span></a> bytes</code></em>,
                                                         <em class="parameter"><code><a class="link" href="gnome-vfs-2.0-gnome-vfs-file-size.html#GnomeVFSFileSize" title="GnomeVFSFileSize"><span class="type">GnomeVFSFileSize</span></a> *bytes_read</code></em>);</pre>
<p>
Read <em class="parameter"><code>bytes</code></em> from <em class="parameter"><code>handle</code></em>.  As with Unix system calls, the number of
bytes read can effectively be less than <em class="parameter"><code>bytes</code></em> on return and will be
stored in <em class="parameter"><code>bytes_read</code></em>.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>handle</code></em> :</span></p></td>
<td>handle of the file to read data from.
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>buffer</code></em> :</span></p></td>
<td>pointer to a buffer that must be at least <em class="parameter"><code>bytes</code></em> bytes large.
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>bytes</code></em> :</span></p></td>
<td>number of bytes to read.
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>bytes_read</code></em> :</span></p></td>
<td>pointer to a variable that will hold the number of bytes
effectively read on return.
</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td> an integer representing the result of the operation.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="gnome-vfs-write"></a><h3>gnome_vfs_write ()</h3>
<pre class="programlisting"><a class="link" href="gnome-vfs-2.0-gnome-vfs-result.html#GnomeVFSResult" title="enum GnomeVFSResult"><span class="returnvalue">GnomeVFSResult</span></a>      gnome_vfs_write                     (<em class="parameter"><code><span class="type">GnomeVFSHandle</span> *handle</code></em>,
                                                         <em class="parameter"><code><span class="type">gconstpointer</span> buffer</code></em>,
                                                         <em class="parameter"><code><a class="link" href="gnome-vfs-2.0-gnome-vfs-file-size.html#GnomeVFSFileSize" title="GnomeVFSFileSize"><span class="type">GnomeVFSFileSize</span></a> bytes</code></em>,
                                                         <em class="parameter"><code><a class="link" href="gnome-vfs-2.0-gnome-vfs-file-size.html#GnomeVFSFileSize" title="GnomeVFSFileSize"><span class="type">GnomeVFSFileSize</span></a> *bytes_written</code></em>);</pre>
<p>
Write <em class="parameter"><code>bytes</code></em> into the file opened through <em class="parameter"><code>handle</code></em>.  As with Unix system
calls, the number of bytes written can effectively be less than <em class="parameter"><code>bytes</code></em> on
return and will be stored in <em class="parameter"><code>bytes_written</code></em>.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>handle</code></em> :</span></p></td>
<td>handle of the file to write data to.
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>buffer</code></em> :</span></p></td>
<td>pointer to the buffer containing the data to be written.
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>bytes</code></em> :</span></p></td>
<td>number of bytes to write.
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>bytes_written</code></em> :</span></p></td>
<td>pointer to a variable that will hold the number of bytes
effectively written on return.
</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td> an integer representing the result of the operation.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="gnome-vfs-seek"></a><h3>gnome_vfs_seek ()</h3>
<pre class="programlisting"><a class="link" href="gnome-vfs-2.0-gnome-vfs-result.html#GnomeVFSResult" title="enum GnomeVFSResult"><span class="returnvalue">GnomeVFSResult</span></a>      gnome_vfs_seek                      (<em class="parameter"><code><span class="type">GnomeVFSHandle</span> *handle</code></em>,
                                                         <em class="parameter"><code><a class="link" href="gnome-vfs-2.0-gnome-vfs-file-rw-ops.html#GnomeVFSSeekPosition" title="enum GnomeVFSSeekPosition"><span class="type">GnomeVFSSeekPosition</span></a> whence</code></em>,
                                                         <em class="parameter"><code><a class="link" href="gnome-vfs-2.0-gnome-vfs-file-size.html#GnomeVFSFileOffset" title="GnomeVFSFileOffset"><span class="type">GnomeVFSFileOffset</span></a> offset</code></em>);</pre>
<p>
Set the current position for reading/writing through <em class="parameter"><code>handle</code></em>.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>handle</code></em> :</span></p></td>
<td>handle for which the current position must be changed.
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>whence</code></em> :</span></p></td>
<td>integer value representing the starting position.
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>offset</code></em> :</span></p></td>
<td>number of bytes to skip from the position specified by <em class="parameter"><code>whence</code></em>.
(a positive value means to move forward; a negative one to move backwards).
</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td> an integer representing the result of the operation.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="gnome-vfs-tell"></a><h3>gnome_vfs_tell ()</h3>
<pre class="programlisting"><a class="link" href="gnome-vfs-2.0-gnome-vfs-result.html#GnomeVFSResult" title="enum GnomeVFSResult"><span class="returnvalue">GnomeVFSResult</span></a>      gnome_vfs_tell                      (<em class="parameter"><code><span class="type">GnomeVFSHandle</span> *handle</code></em>,
                                                         <em class="parameter"><code><a class="link" href="gnome-vfs-2.0-gnome-vfs-file-size.html#GnomeVFSFileSize" title="GnomeVFSFileSize"><span class="type">GnomeVFSFileSize</span></a> *offset_return</code></em>);</pre>
<p>
Return the current position on <em class="parameter"><code>handle</code></em>. This is the point in the file
pointed to by handle that reads and writes will occur on.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>handle</code></em> :</span></p></td>
<td>handle for which the current position must be retrieved.
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>offset_return</code></em> :</span></p></td>
<td>pointer to a variable that will contain the current position
on return.
</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td> an integer representing the result of the operation.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="gnome-vfs-forget-cache"></a><h3>gnome_vfs_forget_cache ()</h3>
<pre class="programlisting"><a class="link" href="gnome-vfs-2.0-gnome-vfs-result.html#GnomeVFSResult" title="enum GnomeVFSResult"><span class="returnvalue">GnomeVFSResult</span></a>      gnome_vfs_forget_cache              (<em class="parameter"><code><span class="type">GnomeVFSHandle</span> *handle</code></em>,
                                                         <em class="parameter"><code><a class="link" href="gnome-vfs-2.0-gnome-vfs-file-size.html#GnomeVFSFileOffset" title="GnomeVFSFileOffset"><span class="type">GnomeVFSFileOffset</span></a> offset</code></em>,
                                                         <em class="parameter"><code><a class="link" href="gnome-vfs-2.0-gnome-vfs-file-size.html#GnomeVFSFileSize" title="GnomeVFSFileSize"><span class="type">GnomeVFSFileSize</span></a> size</code></em>);</pre>
<p>
With this call you can announce to gnome-vfs that you will no longer
use the region of data starting at <em class="parameter"><code>offset</code></em> with the size of <em class="parameter"><code>size</code></em>. Any
cached data for this region might then be freed.
</p>
<p>
This might be useful if you stream large files, for example.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>handle</code></em> :</span></p></td>
<td>handle of the file to affect.
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>offset</code></em> :</span></p></td>
<td>start point of the region to be freed.
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>size</code></em> :</span></p></td>
<td>length of the region to be freed (or until the end of the
file if 0 is specified).
</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td> an integer representing the result of the operation.

</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 2.12</p>
</div>
</div>
</div>
<div class="footer">
<hr>
          Generated by GTK-Doc V1.15.1</div>
</body>
</html>